/*
 * @(#)IdentityScope.java	1.35 01/12/12
 *
 * 版权所有2002 Sun MicroSystems，Inc.保留所有权利。Sun专有/机密。使用受许可条款的约束。
 */
 
package java.security;

import java.io.Serializable;
import java.util.Enumeration;
import java.util.Properties;

/** 
 * <p>此类表示标识的作用域。它本身就是一个身份，因此有一个名称和一个作用域。它还可以有选择地具有公钥和相关证书。
 *
 * 身份作用域可以包含所有类型的身份对象，包括Signer。所有类型的身份对象都可以使用相同的方法进行检索、添加和删除。
 * 请注意，不同类型的身份作用域可能会对不同类型的身份应用不同的策略进行不同的操作。
 *
 * 键和标识之间存在一对一的映射，并且每个作用域只能有一个键的一个副本。例如，假设<b>Acme Software，Inc.</b>是用户已知的软件发行商。
 * 假设它是一个身份，即它有一个公钥和一组关联的证书。它在作用域中使用名称“Acme Software”命名。
 * 作用域中的其他命名标识没有相同的公钥。当然，它们的名字都不一样。
 *
 * @see Identity
 * @see Signer
 * @see Principal
 * @see Key
 *
 * @version 	1.31, 01/27/97
 * @author Benjamin Renaud */
public abstract 
class IdentityScope extends Identity {

    /* The system's scope */
    private static IdentityScope scope;

    // initialize the system scope
    private static void initializeSystemScope() {

	String classname = Security.getProperty("system.scope");

	if (classname == null) {
	    return;

        } else {

	    try {
		Class.forName(classname);
	    } catch (ClassNotFoundException e) {
		Security.error("unable to establish a system scope from " +
			       classname);
		e.printStackTrace();
	    }
	}
    }

    /**
     * 此构造函数仅用于序列化，不应由子类使用。
     */
    protected IdentityScope() {
	this("restoring...");
    }

    /**
     * Constructs a new identity scope with the specified name.
     *
     * @param name the scope name.
     */
    public IdentityScope(String name) {
	super(name);
    }

    /**
     * Constructs a new identity scope with the specified name and scope.
     * 
     * @param name the scope name.
     * @param scope the scope for the new identity scope.
     * 
     * @exception 如果作用域中已存在同名的标识，则引发KeyManagement异常。
     */
    public IdentityScope(String name, IdentityScope scope) 
    throws KeyManagementException {
	super(name, scope);
    }

    /**
     * 返回系统的标识范围。请参阅<a href>Java加密体系结构API规范&参考</a>中的“系统标识范围”部分。
     * 
     * @return the system's identity scope.
     */
    public static IdentityScope getSystemScope() {
	if (scope == null) {
	    initializeSystemScope();
	}
	return scope;
    }


    /**
     * 设置系统的标识范围。请参阅<a href>Java加密体系结构API规范&参考</a>中的“系统标识范围”部分。
     *
     * @param scope the scope to set.
     */
    protected static void setSystemScope(IdentityScope scope) {
	staticCheck("set.system.scope");
	IdentityScope.scope = scope;
    }

    /**
     * 返回此标识范围内的标识数。
     * 
     * @return the number of identities within this identity scope.
     */
    public abstract int size();

    /**
     * 返回此作用域中具有指定名称(如果有)的标识。
     * 
     * @param name the name of the identity to be retrieved.
     * 
     * @return 名为<code>name</code>的标识，如果此作用域中没有名为<code>name</code>的标识，则返回NULL。
     */
    public abstract Identity getIdentity(String name);

    /**
     * 检索名称与指定主体的名称相同的标识。(注：Identity实现主体。)
     *
     * @param principal the principal corresponding to the identity
     * to be retrieved.
     * 
     * @return 名称与主体的名称相同的标识，如果此作用域中没有同名的标识，则为NULL。
     */
    public Identity getIdentity(Principal principal) {
	return getIdentity(principal.getName());
    }

    /**
     * Retrieves the identity with the specified public key.
     *
     * @param key the public key for the identity to be returned.
     *
     * @return 具有给定键的标识，如果此作用域中没有具有该键的标识，则返回NULL。
     */
    public abstract Identity getIdentity(PublicKey key);

    /**
     * Adds an identity to this identity scope.
     *
     * @param identity the identity to be added.
     *
     * @exception 如果标识无效、发生名称冲突、另一个标识与要添加的标识具有相同的公钥或发生另一个异常，则引发KeyManagement异常。
     * */
    public abstract void addIdentity(Identity identity) 
    throws KeyManagementException;

    /**
     * Removes an identity from this identity scope.
     *
     * @param identity the identity to be removed.
     *
     * @exception KeyManagementException if the identity is missing,
     * or another exception occurs.
     */
    public abstract void removeIdentity(Identity identity) 
    throws KeyManagementException;

    /**
     * 返回此标识作用域中所有标识的枚举。
     * 
     * @return an enumeration of all identities in this identity scope.
     */
    public abstract Enumeration identities();

    /**
     * 返回此标识作用域的字符串表示形式，包括其名称、作用域名和此标识作用域中的标识数。
     *
     * @return a string representation of this identity scope.
     */
    public String toString() {
	return super.toString() + "[" + size() + "]";
    }
}
